home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / ultra250.zip / UW_HELP5.HLP < prev    next >
Text File  |  1992-11-03  |  31KB  |  733 lines
  1. `co(4,7);────────────────────────── /// General Macros ────────────────────────────────`co();
  2.     UltraWin also makes extensive use of macros ( defined in UW.H ) for simple
  3.     operations that do not justify the overhead of a function, and make your
  4.     programs more readable.  The following are for general use.
  5.  
  6. `co(10,1);/// hibyte`co();
  7.     #define hibyte(c)              (uchar) ((c) >> 8)
  8.     Yields the most significant byte of integer c.
  9.  
  10. `co(10,1);/// lobyte`co();
  11.     #define lobyte(c)              (uchar) ((c) & 0x00ff)
  12.     Yields the least significant byte of integer c.
  13.  
  14. `co(10,1);/// lower`co();
  15.     #define lower (x, y)         (x < y) ? x : y
  16.     Yields the lesser of the values x and y.
  17.  
  18. `co(10,1);/// range`co();
  19.     #define range(l,b,h)         ((((b) >= (l)) && ((b) <= (h))))
  20.     Yields a 1 if b is between l and h inclusive.
  21.  
  22. `co(10,1);/// swap`co();
  23.     #define swap(a,b,c)          ((c) = (a), (a) = (b), (b) = (c))
  24.     Swaps the values a and b utilizing a temporary c.
  25.  
  26. `co(10,1);/// upper`co();
  27.     #define upper (x, y)         (x > y) ? x : y
  28.   Yields the greater of the values x and y.
  29.  
  30. `co(4,7);────────────────────────── /// Window Macros ─────────────────────────────────`co();
  31.     Many of the things you do with windows are only accomplished with the
  32.     window macros.  The macros will allow you to perform several forms of
  33.     input/output to a window, change the window attributes, move the window
  34.     cursor within the window, and more.  Nearly every access performed on
  35.     a window structure can be done using these macros.  We recommend the use
  36.     of these macros wherever possible as it allows us to "hide" the data
  37.     structure, a common OOP technique. A close look at these macros will
  38.     give you some insight into how UltraWin uses the window structure.
  39.  
  40. `co(10,1);/// cls`co();
  41.     #define cls()                                 (setmem(Screen, V_cols * V_rows * 2, 0))
  42.     Clears the entire screen to black.
  43.  
  44. `co(10,1);/// mv_cs`co();
  45.     #define mv_cs(c,r,wnp)                ((wnp)->csr_x = (c), (wnp)->csr_y = (r))
  46.     Moves the "soft" cursor in window wnp to the column and row c and r.
  47.     
  48. `co(10,1);/// wn_att`co();
  49.     #define wn_att(a,wnp)                 ((wnp)->att = (a))
  50.     Sets the window attribute in wnp to the value a.
  51.  
  52. `co(10,1);/// wn_bdratt`co();
  53.     #define wn_bdratt(a,wnp)            ((wnp)->bdr_att = (a))
  54.     Sets the window border attribute in wnp to the value a.    This is
  55.     the complement to the wn_att macro.
  56.     
  57. `co(10,1);/// wn_bdr_color`co();
  58.     #define wn_bdr_color(f,b,wnp) ((wnp)->bdr_att = ((b) << 4) | (f))
  59.     Sets the border foreground and background colors in window wnp.  This
  60.     is the complement to the wn_color macro.
  61.  
  62. `co(10,1);/// wn_color`co();
  63.     #define wn_color(f,b,wnp)         ((wnp)->att = ((b) << 4) | (f))
  64.     Sets the foreground and background colors in window wnp.    This is
  65.     done by setting the window attribute accordingly.
  66.     
  67. `co(10,1);/// wn_name`co();
  68.     #define wn_name(n, wnp)             ((wnp)->name = (n))
  69.     Sets the name at the top of window wnp to the string n.
  70.  
  71. `co(10,1);/// wn_name_loc`co();
  72.     #define wn_name_loc(l, wnp)     ((wnp)->name_loc = (l))
  73.     Sets the location of the name in window wnp to left, right, or
  74.     centered.
  75.  
  76. `co(10,1);/// wn_read`co();
  77.     #define wn_read( wnp )                (wn_io( IN, BUFF, (wnp)))
  78.     Pulls what is actually on the screen under the window into the
  79.     window itself!    This is like wn_save, but instead of pulling the
  80.     area under the window into the save/restore buffer, it pulls it
  81.     into the window.
  82.  
  83. `co(10,1);/// wn_restore`co();
  84.     #define wn_restore( wnp )         (wn_io(OUT, SAVE, (wnp)))
  85.     Restores the area saved (by the macro wn_save) under the window wnp.
  86.     
  87. `co(10,1);/// wn_rfsh`co();
  88.     #define wn_rfsh( wnp )                (wn_io(OUT, BUFF, (wnp)))
  89.     Redraws (refreshes) the window wnp. 
  90.  
  91. `co(10,1);/// wn_save`co();
  92.     #define wn_save( wnp )                (wn_io( IN, SAVE, (wnp)))
  93.     Saves the area under the window wnp to the window save area for later
  94.     restoration.
  95.  
  96. `co(10,1);/// wn_get_att`co();
  97.   #define wn_get_att(wnp)                 ((wnp)->att)
  98.   Returns the current window attribute. (See wn_att to set).
  99. `co(10,1);/// wn_get_bdratt`co();
  100.     #define wn_get_bdratt(wnp)             ((wnp)->bdr_att)
  101.   Returns the current window border attribute. (See wn_bdratt to set).
  102.  
  103. `co(10,1);/// wn_get_bdr_style`co();
  104.     #define wn_get_bdr_style(wnp)         ((wnp)->bdr_style)
  105.   Returns the current window border style. (SGL_BDR,DBL_BDR,SLD_BDR,DUAL_BDR)
  106. `co(10,1);/// wn_set_bdr_style`co();
  107.     #define wn_set_bdr_style(state,wnp)      ((wnp)->bdr_style = state)
  108.     Sets the window border style.  You must call wn_border to redraw.
  109.  
  110. `co(10,1);/// wn_get_cols`co();
  111.     #define wn_get_cols(wnp)               ((wnp)->cols)
  112.   Returns the number of columns in the window, counting any border.
  113.   NOTE: There is no set macro as the columns cannot be changed directly.
  114.  
  115. `co(10,1);/// wn_get_csr_x`co();
  116.     #define wn_get_csr_x(wnp)           ((wnp)->csr_x)
  117.   Returns the window's current cursor x position.
  118. `co(10,1);/// wn_set_csr_x`co();
  119.     #define wn_set_csr_x(x,wnp)           ((wnp)->csr_x = x)
  120.   Sets the window's current cursor x position.
  121.  
  122. `co(10,1);/// wn_get_csr_y`co();
  123.     #define wn_get_csr_y(wnp)           ((wnp)->csr_y)
  124.   Returns the window's current cursor y position.
  125. `co(10,1);/// wn_set_csr_y`co();
  126.     #define wn_set_csr_y(y,wnp)           ((wnp)->csr_y = y)
  127.   Sets the window's current cursor y position.
  128.  
  129. `co(10,1);/// wn_get_name_loc`co();
  130.     #define wn_get_name_loc(wnp)           ((wnp)->name_loc)
  131.   Returns the window's current name location. (CENTERED,LEFT_JUST,RIGHT_JUST)
  132. `co(10,1);/// wn_set_name_loc`co();
  133.     #define wn_set_name_loc(state,wnp)        ((wnp)->name_loc = state)
  134.   Sets the window's name location.  Call wn_border to redraw.
  135.  
  136. `co(10,1);/// wn_get_rows`co();
  137.     #define wn_get_rows(wnp)                 ((wnp)->rows)
  138.   Returns the number of rows in the window, counting any border.
  139.   NOTE: There is no set macro as the rows cannot be changed directly.
  140.  
  141. `co(10,1);/// wn_is_bell_flag`co();
  142.     #define wn_is_bell_flag(wnp)        ((wnp)->bell_flag)  
  143.   Returns the state of the bell process flag.  If wn_st_fmt() is used, and
  144.   this bit is set, a tone is sounded when a bell character is encountered.
  145. `co(10,1);/// wn_set_bell_flag`co();
  146.     #define wn_set_bell_flag(state,wnp)    ((wnp)->bell_flag = state)
  147.     Sets the state of the bell flag.
  148.  
  149. `co(10,1);/// wn_is_bk_flag`co();
  150.     #define wn_is_bk_flag(wnp)          ((wnp)->bk_flag)    
  151.   Returns the state of the backspace process flag.  If wn_st_fmt() is used,
  152.   and this bit is set, a backspace will cause the cursor to move back one
  153.   space and delete the character.
  154. `co(10,1);/// wn_set_bk_flag`co();
  155.     #define wn_set_bk_flag(state,wnp)      ((wnp)->bk_flag = state)
  156.     Sets the state of backspace flag.
  157.  
  158. `co(10,1);/// wn_is_bs_clear`co();
  159.     #define wn_is_bs_clear(wnp)         ((wnp)->bs_clear)   
  160.     Returns the state of the backspace clear flag.  This is used by the 
  161.     function `keyword(wn_bksp,[uw_help2.hlp]/// wn_bksp); in uw_term.c and is used for terminal emulation support.
  162.     If set, a backspace will clear the previous character, otherwise, it will
  163.     simply move back one character, leaving the character unchanged.
  164. `co(10,1);/// wn_set_bs_clear`co();
  165.     #define wn_set_bs_clear(state,wnp)     ((wnp)->bs_clear = state)
  166.     Sets the state of the backspace clear flag.
  167.  
  168. `co(10,1);/// wn_is_cr_flag`co();
  169.     #define wn_is_cr_flag(wnp)          ((wnp)->cr_flag)    
  170.   Returns the state of the carriage return flag.  If wn_st_fmt() is used,
  171.   and this bit is set, a carriage return will cause the cursor to move to
  172.   the first column of the current row. NOTE: The cursor is not moved
  173.   to the next row.  (See wn_is_lf_flag).
  174. `co(10,1);/// wn_set_cr_flag`co();
  175.     #define wn_set_cr_flag(state,wnp)      ((wnp)->cr_flag = state)
  176.   Sets the state of the carriage return flag.
  177.  
  178. `co(10,1);/// wn_is_cr_lf_flag`co();
  179.     #define wn_is_cr_lf_flag(wnp)       ((wnp)->cr_lf_flag) 
  180.   Returns the state of the carriage return/line feed flag.  If wn_st_fmt()
  181.   is used, and this bit is set, a carriage return OR line feed will cause
  182.   the cursor to move to the first column of the next line.
  183. `co(10,1);/// wn_set_cr_lf_flag`co();
  184.     #define wn_set_cr_lf_flag(state,wnp)   ((wnp)->cr_lf_flag = state)
  185.   Sets the state of the carriage return/line feed flag.
  186.  
  187. `co(10,1);/// wn_is_csr_adv`co();
  188.     #define wn_is_csr_adv(wnp)          ((wnp)->csr_adv)    
  189.   Returns the state of the cursor advance flag.  If this bit is set, the
  190.   window cursor is automatically adjusted as text is written in the window.
  191. `co(10,1);/// wn_set_csr_adv`co();
  192.     #define wn_set_csr_adv(state,wnp)      ((wnp)->csr_adv = state)
  193.   Sets the state of the cursor advance flag.
  194.  
  195. `co(10,1);/// wn_is_eol_wrap`co();
  196.     #define wn_is_eol_wrap(wnp)         ((wnp)->eol_wrap)   
  197.   Returns the state of the end-of-line flag.  If this bit is set, the
  198.   window cursor is automatically wrapped to the next line when the right
  199.   most column is filled.  The window will scroll if wn_is_scroll_flag
  200.   is also set.
  201. `co(10,1);/// wn_set_eol_wrap`co();
  202.     #define wn_set_eol_wrap(state,wnp)     ((wnp)->eol_wrap = state)
  203.   Sets the state of the end-of-line flag.
  204.  
  205. `co(10,1);/// wn_is_hidden`co();
  206.     #define wn_is_hidden(wnp)              ((wnp)->hidden)     
  207.   Returns the state of the window hidden flag.  If this bit is set, the
  208.   window is completely hidden by other windows on the screen.
  209. `co(10,1);/// wn_set_hidden`co();
  210.     #define wn_set_hidden(state,wnp)         ((wnp)->hidden = state)
  211.   Sets the state of the window hidden flag. (Not typically done by user).
  212.  
  213. `co(10,1);/// wn_is_inside`co();
  214.     #define wn_is_inside(wnp)           ((wnp)->inside)     
  215.   Returns the state if the window inside flag.  If this bit is set, the
  216.   window is bordered and text output takes place inside the border.  If 0,
  217.   position 0,0 is the upper left corner of the border, not one character
  218.   to the right and down.
  219. `co(10,1);/// wn_set_inside`co();
  220.     #define wn_set_inside(state,wnp)       ((wnp)->inside = state)
  221.   Sets the state of the inside flag.
  222.  
  223. `co(10,1);/// wn_is_lf_flag`co();
  224.     #define wn_is_lf_flag(wnp)          ((wnp)->lf_flag)    
  225.   Returns the state of the line feed flag.  If wn_st_fmt() is used, and
  226.   this bit is set, a line feed will cause the cursor to move down one line.
  227.   NOTE: The cursor is not moved to the first column.  (See wn_is_cr_flag).
  228. `co(10,1);/// wn_set_lf_flag`co();
  229.     #define wn_set_lf_flag(state,wnp)      ((wnp)->lf_flag = state)
  230.     Sets the state of the line feed flag.
  231.  
  232. `co(10,1);/// wn_is_mask_on`co();
  233.     #define wn_is_mask_on(wnp)          ((wnp)->mask_on)    
  234.   Returns the state of the window mask flag.  If set, this window is
  235.   involved in output masking.
  236. `co(10,1);/// wn_set_mask_on`co();
  237.     #define wn_set_mask_on(state,wnp)      ((wnp)->mask_on = state)
  238.   Sets the state of the mask flag. (Not typically done by user).
  239.  
  240. `co(10,1);/// wn_is_mgr_flag`co();
  241.     #define wn_is_mgr_flag(wnp)         ((wnp)->mgr_flag)   
  242.   Returns the state of the window manager flag.  If set, the window is in
  243.   the window manager's linked list.
  244. `co(10,1);/// wn_set_mgr_flag`co();
  245.     #define wn_set_mgr_flag(state,wnp)     ((wnp)->mgr_flag = state)
  246.   Sets the state of the window manager flag. (Not typically done by user).
  247.  
  248. `co(10,1);/// wn_is_overlapped`co();
  249.     #define wn_is_overlapped(wnp)       ((wnp)->overlapped) 
  250.   Returns the state of the window overlapped flag.  If set, another window 
  251.   partially overlaps this window.
  252. `co(10,1);/// wn_set_overlapped`co();
  253.     #define wn_set_overlapped(state,wnp)   ((wnp)->overlapped = state)
  254.   Sets the state of the overlapped flag. (Not typically done by user).
  255.  
  256. `co(10,1);/// wn_is_popup`co();
  257.     #define wn_is_popup(wnp)              ((wnp)->popup)      
  258.   This returns the state of the window popup flag.  If set, the window 
  259.   is a popup window, saving the area under it for later restoration.
  260. `co(10,1);/// wn_set_popup`co();
  261.     #define wn_set_popup(state,wnp)           ((wnp)->popup = state)
  262.   Sets the state of the popup flag. (Not typically done by user).
  263.  
  264. `co(10,1);/// wn_is_scroll`co();
  265.     #define wn_is_scroll(wnp)           ((wnp)->scroll)     
  266.   This returns the state of the window scroll flag.  If set, and csr_adv
  267.   is also set, the window will scroll when the last character of the window
  268.   is written to.
  269. `co(10,1);/// wn_set_scroll`co();
  270.     #define wn_set_scroll(state,wnp)       ((wnp)->scroll = state)
  271.   Sets the state of the scroll flag.
  272.  
  273. `co(10,1);/// wn_is_set_flag`co();
  274.     #define wn_is_set_flag(wnp)         ((wnp)->set_flag)   
  275.     This returns the state of the window set flag.  If set, the window has
  276.     been placed on the screen.
  277. `co(10,1);/// wn_set_set_flag`co();
  278.     #define wn_set_set_flag(state,wnp)     ((wnp)->set_flag = state)
  279.   Sets the state of the window set flag. (Not typically done by user).
  280.  
  281. `co(10,1);/// wn_is_tab_flag`co();
  282.     #define wn_is_tab_flag(wnp)         ((wnp)->tab_flag)   
  283.   Returns the state of the tab flag.  If wn_st_fmt() is used, and
  284.   this bit is set, a tab will cause the cursor to move one tab to the right.
  285.   See `keyword(Tab Stop Control,[uw_help2.hlp]/// Tab Stop Control); for information on how to set tabs.
  286. `co(10,1);/// wn_set_tab_flag`co();
  287.     #define wn_set_tab_flag(state,wnp)     ((wnp)->tab_flag = state)
  288.   Sets the state of the tab flag.
  289.  
  290. `co(10,1);/// wn_is_w_wrap`co();
  291.     #define wn_is_w_wrap(wnp)           ((wnp)->w_wrap)     
  292.   This returns the state of the word wrap flag.  If set, and wn_st_fmt() is
  293.   used, word wrap will occur within the window.
  294. `co(10,1);/// wn_set_w_wrap`co();
  295.     #define wn_set_w_wrap(state,wnp)       ((wnp)->w_wrap = state)
  296.   Sets the state of the tab flag.
  297.  
  298. `co(4,7);─────────────────────────── /// Font/EGA Control ─────────────────────────────`co();
  299.  
  300.  ┌──────────────────────────────────────────────────────────────────────────┐    
  301.  │          `keyword(encode_color,/// encode_color);                      `keyword(decode_color,/// decode_color);                  │
  302.  │          `keyword(load_font,/// load_font);                         `keyword(save_font,/// save_font);                     │
  303.  │          `keyword(install_font,/// install_font);                      `keyword(get_font_info,/// get_font_info);                 │
  304.  │          `keyword(blink_enable,/// blink_enable);                      `keyword(replicate_enable,/// replicate_enable);              │
  305.  │          `keyword(set_block_ab,/// set_block_ab);                      `keyword(rom8x8,/// rom8x8);                        │
  306.  │          `keyword(rom8x14,/// rom8x14);                           `keyword(rom8x16,/// rom8x16);                       │
  307.  │          `keyword(read_palette,/// read_palette);                      `keyword(read_palette_all,/// read_palette_all);              │
  308.  │          `keyword(write_palette,/// write_palette);                     `keyword(write_palette_all,/// write_palette_all);             │
  309.  └──────────────────────────────────────────────────────────────────────────┘
  310.  
  311.         These functions are specific to EGA/VGA boards and are advanced
  312.     features. We do not attempt to explain all the details and quirks of the
  313.     EGA/VGA video subsystems.  We recommend you have some reference material
  314.     detailing the EGA/VGA video system to supplement the material presented
  315.     here.
  316.  
  317.         UltraWin gives you the ability to use our own EGA/VGA fonts, or create
  318.     your own with our powerful font editor.  UltraWin also lets you use a full
  319.     16 background colors, and even change the EGA/VGA palette.  However, it is
  320.     not possible to actually read the palette registers on an EGA board.  We
  321.     resolve this deficiency by keeping a "shadow" palette that is initialized
  322.     to the standard EGA values.  When you read/write the palette registers,
  323.     you are also accessing this "shadow" area.
  324.  
  325. `co(10,1);/// encode_color`co();   `keyword(source,[UW_FONT.C]~encode_color);
  326.       Takes the individual red, green, and blue color components and encodes
  327.     them into a format suitable for the EGA/VGA palette registers, returning
  328.     this value as an integer. see also `keyword(decode_color,///decode_color);
  329.  
  330. Prototype:
  331.     void encode_color(int r, int g, int b);
  332.  
  333. Parameters:
  334. `co(11,1);    int r, g, b`co();
  335.         Integers containing each color component.
  336.  
  337. Usage:
  338.     int color, r = 2, g = 3, b = 1;
  339.     ...
  340.     color = encode_color( r, g, b );
  341.  
  342. `co(10,1);/// decode_color`co();   `keyword(source,[UW_FONT.C]~decode_color);
  343.       Takes an EGA/VGA color encoded value as it would be stored in a palette
  344.     register and returns the individual Red, Green, and Blue components.  See
  345.     also `keyword(encode_color,/// encode_color);
  346.  
  347. Prototype:
  348.     void decode_color(int color, int *r, int *g, int *b);
  349.  
  350. Parameters:
  351. `co(11,1);    int color;`co();
  352.         The EGA/VGA encoded color value.
  353. `co(11,1);    int *r, *g, *b`co();
  354.         Integer pointers to store each color component.
  355.  
  356. Usage:
  357.     int color, r, g, b;
  358.     color = random(64);
  359.     ...
  360.     decode_color( color, &r, &g, &b );
  361.  
  362. `co(10,1);/// load_font`co();   `keyword(source,[UW_FONT.C]~load_font);
  363.       Loads a font pattern file into memory.  The fonts are stored in raw
  364.     format, with no header information residing in the file.  As an example,
  365.     let's say we have a file containing 256 8x14 characters.  The first
  366.     character's pattern is contained in the first 14 bytes, the second in
  367.     bytes 15-28, and so on.  You should either allocate the appropriate
  368.     number of bytes and pass the pointer to this function or pass the name
  369.     of a sufficiently large global array of bytes. Upon a successful load,
  370.     the function will return the number of scan lines that are in each
  371.     character, or 0 upon failure.  See also `keyword(save_font,///save_font);
  372.  
  373. Prototype:
  374.     int load_font( uchar *font, char *fname );
  375.  
  376. Parameters:
  377. `co(11,1);    uchar *font;`co();
  378.         A pointer to an area large enough to hold the font pattern data.
  379. `co(11,1);    char  *fname;`co();
  380.         A pointer to the filename that contains the font pattern data.
  381.  
  382. Usage:
  383.     uchar Font8x14[256][14];                                  /* global array */
  384.     int Scan_lines;
  385.     ...
  386.     Scan_lines = load_font( Font8x14, "8x14icon.fnt");
  387.  
  388. `co(10,1);/// save_font`co();   `keyword(source,[UW_FONT.C]~save_font);
  389.       Saves a font pattern from memory into a file.  This is the complement
  390.   of `keyword(load_font,/// load_font);
  391.   
  392. Prototype:
  393.     int save_font( uchar *font, char *fname, int scan_lines );
  394.  
  395. Parameters:
  396. `co(11,1);    uchar *font;`co();
  397.         A pointer to an area containing the font pattern data.
  398. `co(11,1);    char  *fname;`co();
  399.         A pointer to the filename to which to save the font data.
  400. `co(11,1);    int   scan_lines;`co();
  401.         The number of scan lines the font contains (typically 8/14/16).
  402.  
  403. Usage:
  404.     uchar Font8x14[256][14];                                  /* global array */
  405.     ...
  406.     save_font( Font8x14, "8x14ICON.FNT", 14 );
  407.  
  408. `co(10,1);/// install_font`co();   `keyword(source,[UW_FONT.C]~install_font);
  409.       Installs a font loaded into memory, into the EGA/VGA bios area.  Two
  410.     sets of 256 characters can be resident at one time.  The "block" parameter
  411.     determines which set to install.  If "setmode" is non-zero, the video mode
  412.     will be reset.
  413.   
  414. Prototype:
  415.     void install_font( uchar *font, int block, int offset, int cnt,
  416.                                          int scan_lines, int setmode );
  417.  
  418. Parameters:
  419. `co(11,1);    uchar *font;`co();
  420.         A pointer to an area containing the font pattern data.
  421. `co(11,1);    int   block;`co();
  422.         The character set in which to load this font. (0 or 1).
  423. `co(11,1);    int   offset;`co();
  424.         The character offset to load the new font data, typically 0.
  425. `co(11,1);    int   cnt;`co();
  426.         The number of characters to install (max 256).
  427. `co(11,1);    int   scan_lines;`co();
  428.         The number of scan_lines the font contains (typically 8/14/16).
  429. `co(11,1);    int   set_mode;`co();
  430.         If non-zero, the video mode will be reset.
  431.  
  432. Usage:
  433.     uchar Font8x14[256][14];                                  /* global array */
  434.     ...
  435.     load_font( Font8x14, "8x14icon.fnt" );
  436.   install_font( Font8x14, 1, 0, 256, 14, 0 );
  437.  
  438. `co(10,1);/// get_font_info`co();   `keyword(source,[UW_FONT.C]~get_font_info);
  439.       Returns the address, number of scan_lines and video character rows of
  440.     the current font.
  441.     
  442. Prototype:
  443.     uchar far *get_font_info( int type, int *scan_lines, int *rows );
  444.  
  445. Parameters:
  446. `co(11,1);    int   type;`co();
  447.     2 - get address of ROM 8x14 font
  448.     3 - get address of ROM 8x8 font
  449.     4 - get address of second half of ROM 8x8 font
  450.     5 - get address of ROM 9x14 alternate font
  451.     6 - get address of ROM 8x16 font
  452.     7 - get address of ROM 9x16 alternate font
  453. `co(11,1);    int   *scan_lines;`co();
  454.         A pointer to an integer in which to store the number of scan lines in 
  455.     the current font.
  456. `co(11,1);    int   *rows;`co();
  457.         A pointer to an integer in which to store the number of character rows
  458.     for the current screen mode.
  459.  
  460. Usage:
  461.     int scan_lines, rows;
  462.     uchar far  *font;
  463.     ...
  464.     font = get_font_info( 2, &scan_lines, &rows );
  465.  
  466. `co(10,1);/// blink_enable`co();   `keyword(source,[UW_FONT.C]~blink_enable);
  467.       Enables or disables blinking on EGA/VGA systems. When the blink bit is
  468.     disabled, all 256 possible color combinations (16 foreground, 16
  469.     background) can be displayed at one time with no blinking.  If enabled,
  470.     those character cells whose background color is 8-15 will blink.
  471.  
  472. Prototype:
  473.     void blink_enable(int state);
  474.  
  475. Parameters:
  476. `co(11,1);    int   state;`co();
  477.         1 to enable blink, 0 to disable blink.
  478.  
  479. Usage:
  480.     ...
  481.     blink_enable(1);
  482.  
  483. `co(10,1);/// replicate_enable`co();   `keyword(source,[UW_FONT.C]~replicate_enable);
  484.       Enables or disables 9th pixel replication for the 32 characters 0xC0 -
  485.     0xDF on EGA/VGA boards.  The use of this function depends on the video
  486.     card in use.  Some cards (especially in monochrome modes) use a 9 pixel
  487.     wide cell, even though the font is only 8 pixels wide. This usually causes
  488.     no problem as the hardware hides this from us.  However, when performing
  489.     line drawing or other operations where characters must join, a gap may
  490.     exist.  The hardware is capable of replicating the 8th bit into the 9th
  491.     bit to allow for continuous characters. The hardware only does this for
  492.     the line drawing character block 0xC0 - 0xDF. In short, if you modify your
  493.     own fonts and create new borders, lines, etc. that need to be continuous,
  494.     it is recommended that you store these characters in this area and enable
  495.     replication.  No other character cells will be affected.
  496.  
  497. Prototype:
  498.     void replicate_enable(int state);
  499.  
  500. Parameters:
  501. `co(11,1);    int   state;`co();
  502.         1 to enable 9th pixel replication, 0 to disable replication.
  503.  
  504. Usage:
  505.     ...
  506.     replicate_enable(1);
  507.  
  508. `co(10,1);/// set_block_ab`co();   `keyword(source,[UW_FONT.C]~set_block_ab);
  509.       Sets the two possible active fonts as primary and secondary.  Both
  510.     blocks can be set to the same mode.  For example, if we load a standard
  511.     8x14 font into block 0, and an 8x14 icon font into block 1, we might say
  512.     "set_block_ab(0,1)".  This sets the 8x14 as the primary font and the icon
  513.     font as secondary. (Displayed if the background is 8-15).  If
  514.     "set_block_ab(1,0)" is called, the two fonts will be effectively switched.
  515.     "Set_block_ab(0,0)" will always display the 8x14 font regardless of
  516.     attribute settings.
  517.  
  518. Prototype:
  519.     void set_block_ab(int a, int b);
  520.  
  521. Parameters:
  522. `co(11,1);    int   a;`co();
  523.         0 - set font 0 as primary font, 1 - set font 0 as alternate font.
  524. `co(11,1);    int   b;`co();
  525.         0 - set font 1 as primary font, 1 - set font 1 as alternate font.
  526.  
  527. Usage:
  528.     ...
  529.     load_font( Font8x14, "8x14.fnt" );
  530.   install_font( Font8x14, 0, 0, 256, 14, 0 );
  531.     load_font( Font8x14, "8x14icon.fnt" );
  532.   install_font( Font8x14, 1, 0, 256, 14, 0 );
  533.     set_block_ab(0,1);            /* 8x14 - block 0, 8x14icon block 1 */
  534.  
  535. `co(10,1);/// rom8x8`co();   `keyword(source,[UW_FONT.C]~rom8x8);
  536.       Loads the video BIOS 8x8 font into the desired block and optionally
  537.     resets the video mode
  538.  
  539. Prototype:
  540.     void rom8x8(int block, int setmode);
  541.  
  542. Parameters:
  543. `co(11,1);    int   block;`co();
  544.         0 - load font into block 0, 1 - load font into block 1.
  545. `co(11,1);    int   setmode;`co();
  546.         0 - do not reset video mode. 1- set video mode.
  547.  
  548. Usage:
  549.     ...
  550.     rom8x8(0,1);                                    /* load as primary, reset video mode  */
  551.  
  552. `co(10,1);/// rom8x14`co();   `keyword(source,[UW_FONT.C]~rom8x14);
  553.       Loads the video BIOS 8x14 font into the desired block and optionally
  554.     resets the video mode.
  555.  
  556. Prototype:
  557.     void rom8x14(int block, int setmode);
  558.  
  559. Parameters:
  560. `co(11,1);    int   block;`co();
  561.         0 - load font into block 0, 1 - load font into block 1.
  562. `co(11,1);    int   setmode;`co();
  563.         0 - do not reset video mode. 1- set video mode.
  564.  
  565. Usage:
  566.     ...
  567.     rom8x14(1,0);                                    /* load as alternate, don't reset     */
  568.  
  569. `co(10,1);/// rom8x16`co();   `keyword(source,[UW_FONT.C]~rom8x16);
  570.       Loads the video BIOS 8x16 font into the desired block and optionally
  571.     resets the video mode (VGA only).
  572.  
  573. Prototype:
  574.     void rom8x16(int block, int setmode);
  575.  
  576. Parameters:
  577. `co(11,1);    int   block;`co();
  578.         0 - load font into block 0, 1 - load font into block 1.
  579. `co(11,1);    int   setmode;`co();
  580.         0 - do not reset video mode. 1- set video mode.
  581.  
  582. Usage:
  583.     ...
  584.     rom8x16(0,0);                                    /* load as primary, don't reset mode  */
  585.  
  586. `co(10,1);/// read_palette`co();   `keyword(source,[UW_FONT.C]~read_palette);
  587.       Reads a single palette register and returns the value. To determine the
  588.     RGB components, see `keyword(decode_color,/// decode_color); above.
  589.  
  590. Prototype:
  591.     int read_palette( int pnum );
  592.  
  593. Parameters:
  594. `co(11,1);    int   pnum;`co();
  595.         The color palette index to read (0-15).
  596.  
  597. Usage:
  598.     int color;
  599.     ...
  600.     color = read_palette(6);
  601.  
  602. `co(10,1);/// read_palette_all`co();   `keyword(source,[UW_FONT.C]~read_palette_all);
  603.       Reads all 16 palette registers and stores the values into the desired
  604.     area.
  605.  
  606. Prototype:
  607.     void read_palette_all( uchar *vals );
  608.  
  609. Parameters:
  610. `co(11,1);    uchar  *vals;`co();
  611.         A pointer to an array (at least 16 bytes) in which to store the values.
  612.  
  613. Usage:
  614.     uchar colors[16];
  615.     ...
  616.     read_palette_all(colors);
  617.  
  618. `co(10,1);/// write_palette`co();   `keyword(source,[UW_FONT.C]~write_palette);
  619.       Writes a value to a single palette register.  To specify the color in
  620.     RGB components, see `keyword(encode_color,/// encode_color); above.
  621.  
  622. Prototype:
  623.     void write_palette( int pnum, uchar val );
  624.  
  625. Parameters:
  626. `co(11,1);    int   pnum;`co();
  627.         The color palette index to write (0-15).
  628. `co(11,1);    uchar val;`co();
  629.         The color palette value.
  630.  
  631. Usage:
  632.     ...
  633.   write_palette(6, encode_color(1,3,2));
  634.  
  635. `co(10,1);/// write_palette_all`co();   `keyword(source,[UW_FONT.C]~write_palette_all);
  636.       Writes values to all palette registers.
  637.  
  638. Prototype:
  639.     void write_palette_all( uchar *vals );
  640.  
  641. Parameters:
  642. `co(11,1);    uchar *vals;`co();
  643.         The 16 color palette values.
  644.  
  645. Usage:
  646.     char palette[16] =
  647.     { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x14,    0x07,
  648.         0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f };
  649.     ...
  650.   write_palette_all(palette);
  651.  
  652. `color(RED,LIGHTGRAY);──────────────────────────  /// Graphics Support ─────────────────────────────`color();
  653.  
  654.       UltraWin is a unique library in that although primarily designed for
  655.     text modes it has the capability to use EGA/VGA graphic modes as well.
  656.     This is due to the flexibility of UltraWin's text output routines.  It was
  657.     a fairly simple task for us to route all text output through one routine
  658.     which places one character on the screen.  This does not slow down normal
  659.     text output whatsoever, as all output is routed through this special g_ch
  660.     function only when the global Graphics flag is set.
  661.   
  662.       Please understand though, UltraWin does not add a graphics libarary or
  663.     any other graphics routines other than the output of a single character.
  664.     All UltraWin output is still cell based.  This is no great limitation as
  665.     you can use a third-party graphics library (or the one bundled with your
  666.     compiler) to do all your lines, polygons, circles, etc.  To get UltraWin
  667.     to use graphics, first use your graphics library to put the video into
  668.     either EGA 640x350x16 or VGA 640x480x16 mode and call `keyword(init_uw_graphics,/// init_uw_graphics);.
  669.     It's that easy!
  670.   
  671.       Since UltraWin gives you this flexibility the library can become quite
  672.   literally hardware independent.  For instance, all that would be necessary
  673.   to make UltraWin work with custom hardware ( or even a dumb terminal )
  674.   would be to write ONE routine (g_ch) that outputs a single character on
  675.   the display device, and then call init_uw_graphics.  All output would then
  676.   go through g_ch.  Please see `keyword(g_ch,/// g_ch); for more information.
  677.  
  678. `co(10,1);/// init_uw_graphics`co();   `keyword(source,[UW_GRAPH.C]~init_uw_graphics);
  679.       Initializes UltraWin to support EGA/VGA graphics output.
  680.  
  681. Prototype:
  682.     int init_uw_graphics( int xres, int yres, int font_rows,
  683.                           int font_spacing, int seg, int off );
  684.  
  685. Parameters:
  686.   Parameters:
  687. `co(11,1);  int xres, yres`co();   - resolution in pixels for EGA/VGA
  688. `co(11,1);  int font_rows`co();    - number of scan lines for current font
  689. `co(11,1);  int font_spacing`co(); - number of scan lines between characters
  690. `co(11,1);  int seg`co();          - graphics segment (-1 sets default 0xa000)
  691. `co(11,1);  int off`co();          - graphics offset  (-1 sets default 0x0000)
  692.  
  693. Usage:
  694.     ...
  695.     init_uw_graphics( 640, 350, 14, 14, -1, -1 );
  696.  
  697. `co(10,1);/// g_ch`co();   `keyword(source,[UW_GRAPH.C]~g_ch);
  698.       Outputs a single character to the graphics screen.  This function will
  699.     not normally be called by you.  It is a very important function for those
  700.     of you interested in using UltraWin in graphic modes.  All UltraWin output
  701.     will go through this routine when the Graphics flag is set.  This feature
  702.     gives you the power to write your own g_ch to support other graphics
  703.     standards, dumb-terminals, and virtually any non-standard hardware.
  704.     (Please note that when the global variable G_opt is set, g_ch will not
  705.     draw if the character is already on the screen in the proper colors.)
  706.  
  707.         It is very important to understand what happens here.  We simply replace
  708.     output routines - no other graphics support is provided - UltraWin works
  709.     exactly as it does in text mode.  It will not save/restore graphics areas
  710.     under windows - you must do this yourself, if you wish.
  711.     
  712.         Also note that this function, along with get_font_info and install_font
  713.     are only compilable under the Borland compilers and Microsoft C 7.00;
  714.     previous versions of Microsoft C will not compile inline assembly.  Users
  715.     of other compilers can link the provided object modules (versions compiled
  716.     under Turbo C and Microsoft C 7.00 are both supplied) into their programs
  717.     if need be.  Of course if you use the library for your compiler, then it
  718.     is all automatic. 
  719.  
  720. Prototype:
  721.     int g_ch( int c, int r, uchar v );
  722.  
  723. Parameters:
  724.   Parameters:
  725. `co(11,1);    int c;`co(); - col (UltraWin col 0-V_cols - 1, not pixel col).
  726. `co(11,1);  int r;`co(); - row (UltraWin row 0-V_rows - 1, not pixel row).
  727. `co(11,1);  int v;`co(); - character value (0-255).
  728.  
  729. Usage:
  730.     ...
  731.     g_ch(10, 15, 'x');
  732.  
  733.